TM 


SpInside Macintosh 


An on-line development prototype of 
Apple’s Inside Macintosh Volumes I-V 


ae k es ieee November : 1 a Apple 
Monitors Setting “Color Ee Deve 


loper Group 


Copyright © 1925-1999 hy Apple Cornputar, Tne. 


COMPATIBILITY GUIDELINES 


About This Chapter 
Compatibility 

General Guidelines 

Memory 

Assembly Language 

Hardware 
Determining the Features of a Machine 
Localization 

iPero, Se Habla Espanol? 

Non-Roman Writing Systems 
Applications in a Shared Environment 
Summary of Compatability Guidelines 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
COMPATIBILITY GUIDELINES ¢ 1 of 16 


ABOUT THIS CHAPTER 


Compatibility is a concern for anyone writing software. For some programmers, 
it's a concern because they want to write software that will run, with little or 
no modification, on all versions of the Macintosh. Other programmers want to 
take advantage of particular software and hardware features; they need to know 
where and when these features are available. 


This chapter gives guidelines for making it more likely that your program will 
run on different versions, present and future, of the Macintosh. It also gives 
tips for writing software that can be easily modified for use in other 
countries. Finally, it explains how to determine what features are available on 
a given machine. 
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COMPATIBILITY 


The key to compatibility is not to depend on things that may change. Inside 
Macintosh contains hundreds of warnings where information is likely to change; 
all of these warnings can be summarized by a single rule: use global variable 
names and system calls, rather than addresses and numeric values. 


At the most basic level, all of the software and hardware components of the 
Macintosh-each line of ROM code, each RAM memory location, each hardware device- 
are represented by numbers. Symbolic names have been defined for virtually 
every routine, variable, data structure, memory location, and hardware device 
that your application will need to use. Use of these names instead of the 
actual numbers will simplify the process of updating your application when the 
numbers change. 


General Guidelines 


Any field that's marked in Inside Macintosh as "not used" should be considered 
"reserved by Apple" and usually be left 0. 


While Inside Macintosh gives the structure of low-level data structures (for 
instance, file control blocks, volume control blocks, and system queues), it's 
best not to access or manipulate these structures directly; whenever possible, 
use the routines provided for doing this. 


You shouldn't rely on system resources being in RAM; on the Macintosh Plus, 
Macintosh SE, and Macintosh II, certain system resources are in ROM. Don't 
assume, for example, that you can regain RAM space by releasing system 
resources. 


A variety of different keyboards are available for the Macintosh; you should 
always read ASCII codes rather than key codes. 


Don't count on the alternate (page 2) sound or video buffers. On the Macintosh 
II, you can determine the number of video pages and switch between them; for 
details, see the Graphics Devices chapter. 


To be compatible with printers connected directly to the Macintosh or via 
AppleTalk, use either the Printing Manager or the Printer Driver's control calls 
for text-streaming and bitmap-printing (as documented in Inside 

Macintosh). Don't send ASCII codes directly to the Printer Driver. In general, 
you should avoid using printer-specific features and should not access the 
fields of the print record directly. 


Memory 


You shouldn't depend on either the system or application heap zones starting at 
certain addresses. Use the global variable ApplZone to find the application 
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heap and the variable SysZone to locate the system heap. You should not count 
on the application heap zone starting at an address less than 65536; in other 
words, don't expect a system heap that's smaller than 64K in size. 


Space in the system heap is extremely limited. In general, avoid using the 
system heap; if you must, allocate only very small objects (about 32 bytes or 
less). If you need memory that won't be reinitialized when your application 
ends, allocate it with an 'INIT' resource; for details, see the System Resource 
File chapter. 


The high-order byte of a master pointer contains flags used by the Memory 
Manager. In the future, all 32 bits of the pointer may be needed, in which case 
the flags byte will have to be moved elsewhere. For this reason, you should 
never set or clear these flags directly but should instead use the Memory 
Manager routines HPurge, HNoPurge, HLock, HUnlock, HSetRBit, HClUrRBit, 
HGetState, and HSetState. 


You should allow for a variety of RAM memory sizes. While 128K, 512K, 1 MB, and 
2 MB are standard sizes, many other RAM configurations are possible. 


NIL handles (handles whose value is zero) are common bugs; they typically come 
from unsuccessful GetResource calls and often result (eventually) in address 
errors. The 68020 does not give address errors when accessing data, so be sure 
to test your code for NIL handles and null pointers. 


Assembly Language 


In general, you shouldn't use 68000 instructions that depend on supervisor mode; 
these include instructions that modify the contents of the Status Register (SR). 
Programmers typically modify the SR only as a means of changing the Condition 
Code Register (CCR) half of the register; an instruction that addresses the CCR 
directly will work fine instead. You should also not use the User Stack Pointer 
or turn interrupts on and off. 


Timing loops that depend on the clock speed of a particular processor will fail 
when faster processors are introduced. You can use the Operating System Utility 
procedure Delay for timing, or you can check the contents of the global variable 
Ticks. For more precise timings, you can use the Time Manager (taking advantage 
of the VIA timers). Several global variables also contain useful timing 
information; they're described in the Start Manager chapter. 


If you wish to handle your own exceptions (thereby relying on the position of 
data in the exception's local stack frame), be aware that exception stack frames 
vary within the 68000 family. 


In particular, don't use the TRAP instruction. Also, the TAS instruction, which 
uses a special read-modify-write memory cycle, is not supported by the Macintosh 
SE and Macintosh II hardware. 


A memory management unit in the Macintosh II may prevent code from writing to 
addresses within code segments. Also, the 68020 caches code as it's 
encountered. Your data blocks should be allocated on the stack or in heap 
blocks separate from the code, and your code should not modify itself. 
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Note: You can determine which microprocessor is installed by calling 
the SysEnvirons function; it's described below. 


The Floating-Point Arithmetic and Transcendental Functions Packages have been 
extended to take advantage of the MC68881 numerics coprocessor; using the 
routines in these packages will ensure compatibility on all current and future 
versions of the Macintosh. (For details on these packages, see the Floating- 
Point Arithmetic and Transcendental Functions Packages chapter. ) 


Memory locations below the system heap that aren't documented may not be 
available for use in future systems. Also, microprocessors in the 68000 family 
use the exception vectors in locations $0 through $FF in different ways. In 
general, don't depend on any global variable that isn't documented in Inside 
Macintosh. 


Don't store information in the application parameters area (the 32 bytes between 
the application globals and the jump table); this space is reserved for use by 
Apple. 


Don't depend on the format of the trap dispatch table. Use the Operating System 
Utility routines GetTrapAddress and SetTrapAddress to access the trap dispatch 
table. You should also not use unassigned entries in the trap table, or any 
other unused low memory location. 


Inside Macintosh documents the values returned by register-based routines; 
don't depend on return values that aren't documented here. 


Hardware 


As a general rule, you should never address hardware directly; whenever 
possible, use the routines provided by the various device drivers. The 
addresses of memory-mapped hardware (like the VIA1, VIA2, SCC, and IWM) are 
always subject to change, and direct access to such hardware may not be 
possible. For instance, the Macintosh II memory-management unit may prevent 
access to memory-mapped hardware. If you must access the hardware directly, 
get the base address of the device from the appropriate global variable; see the 
Macintosh Family Hardware Reference Manual for details. 


Warning: Although there's a global variable that contains the SCSI base 
address, you should use the SCSI Manager; this is especially 
important with regard to asynchronous operation. 


Note: Copy-protection schemes that rely on particular hardware 
characteristics are subject to failure when the hardware changes. 


You should avoid writing directly to the screen; use QuickDraw whenever 
possible. If you must write directly to the screen, don't "hard code" the 
screen size and location. The global variable ScreenBits contains a bit map 
corresponding to the screen being used. ScreenBits.bounds is the size of the 
screen, ScreenBits.baseAddr is the start of the screen, and ScreenBits.rowBytes 
gives the offset between rows. 


Warning: The screen size can exceed 32K; use long word values in screen 
calculations. Also, the screen may be more than one pixel in 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 « Apple Computer 
COMPATIBILITY GUIDELINES ¢ 5 of 16 


depth; see the QuickDraw chapter for details. 


There are many sizes of disks for the Macintosh from Apple, and more from 
third-party vendors. Use the Standard File Package and File Manager calls to 
determine the number and size of disk drives. 
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DETERMINING THE FEATURES OF A MACHINE 


As the Macintosh family grows, applications need a reliable and comprehensive 
way of determining what software and hardware features are available on a given 
machine. Although the Operating System Utilities routine Environs indicates the 
type of machine and ROM version running, it provides no help in distinguishing 
between the plethora of different software feature sets and hardware 
configurations that an application may encounter. 


A new function, SysEnvirons, provides detailed information about what software 
functionality (Color QuickDraw, as an example) is available, as well as what 
hardware devices (processors, peripherals, and so on) are installed or 
connected. 


ALL of the Toolbox Managers must be initialized before calling SysEnvirons. 

In addition, the AppleTalk Manager routine MPPOpen must be called if the driver 
version information in atDrvrVersNum is desired. SysEnvirons is not intended 
for use by device drivers, but can be called from desk accessories. (It does not 
assume that register A5 has been properly set up.) 


FUNCTION SysEnvirons (versionRegested: INTEGER; 
VAR theWorld: SysEnvRec) : OSErr; [Not in ROM] 


eeeClick on the X-Ref button, and refer to Technical Note #129, eee 


Trap macro _SysEnvirons 

On entry AQ: sysEnvRec (pointer) 
DO: versRegested (word) 

On exit AQ: sysEnvRec (pointer) 
DO: result code (word) 


Result codes noErr No error 
envNotPresent SysEnvirons trap not present 
envBadVers Nonpositive version number passed 
envVersTooBig Requested version of SysEnvirons 


call not available 


In theWorld, SysEnvirons returns a system environment record describing the 
features of the machine. Designed to be extendible, SysEnvirons will be updated 
as new features are added, and the system environment record that's returned 
will be expanded. System File 4.1 contains version 1 of SysEnvirons; subsequent 
versions will be incremented by 1. 


The system environment record for version 1 of SysEnvirons contains the 
following fields: 


TYPE SysEnvRec = RECORD 
environsVersion: INTEGER; 


machineType: INTEGER; 
systemVersion: INTEGER; 
processor: INTEGER; 
hasFPU: BOOLEAN; 
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hasColorQD: BOOLEAN; 


keyBoardType: INTEGER; 

atDrvrVersNum: INTEGER; 

sysVRefNum: INTEGER 
END; 


New versions of the call will add fields to this record. To distinguish between 
different versions of the call, and thereby between the different sizes of 
records they return, SysEnvirons returns its version number in the 
environsVersion field. If you request version 2, for instance, but only version 
1 is available, the environsVersion field will contain the value 1, and the 
result code envVersTooBig will be returned. This tells you that only the 
information for version 1 has been returned in SysEnvRec. 


The MPW 2.0 interface files contain code, or "glue", for System file versions 
earlier than 4.1, as well as for the 64K and the Macintosh XL ROMs. The glue 
checks for the existence of the trap at runtime; if the call does not exist, the 
glue fills in all fields of the record except systemVersion and returns the 
result code envNotPresent. 


Assembly- language note: As with the MoveHHi procedure, assembly- language 
programmers using MPW should Link with the glue and 
execute 


JSR SysEnvirons 


If you're using another development system, refer 
to its documentation for details. 


The machineType field returns one of the following constants: 


CONST envMachUnknown 0; {new version of Macintosh--not covered } 
{ by this version of SysEnvirons} 


env512KE — Fol {Macintosh 512K enhanced} 
envMacPLus = 2; {Macintosh Plus} 

envSE = 3; {Macintosh SE} 

envMacII = 4; {Macintosh II} 

envMacIIx = 5; {Macintosh IIx} 
envMacIIcx = 6; {Macintosh IIcx} 

envSE30 = 7; {Macintosh SE/30} 
envPortable = 8; {Macintosh Portable} 
envMacIIci = 9; {Macintosh IIci} 


In addition to these, the glue for SysEnvirons may return one of the following: 


CONST envMac 
envXL 


-1; {Macintosh with 64K ROM} 
-2; {Macintosh XL} 


The systemVersion field returns the version number of the System file 
represented as two byte-long numbers, separated by a period. (It is not a fixed 
point number.) For instance, System 4.1 returns $0410 or 04.10 in this field. 
(Applications can use this for compare operations.) If SysEnvirons is called 
while a system earlier than System 4.1 is running, the glue will return a $0 in 
this field, and the result code envNotPresent will be returned. 


The processor field returns one of the following constants: 
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CONST envCPUUnknown = 0; {new processor--not yet covered by this } 
{ version of SysEnvirons} 
env68000 = 1; {MC68000 processor} 
env68010 =2 {MC68010 processor} 
env68020 = 3; {MC68020 processor} 
env68030 = 4; {MC68030 processor} 


The hasFPU field tells whether or not a Motorola MC68881 floating-point 
coprocessor unit is present. (This field does not apply to third-party memory- 
mapped coprocessor add-ons.) 


The hasColorQD field tells whether or not Color QuickDraw is present. It does 
not indicate whether or not a color screen is present (high-level QuickDraw 
calls provide this information). 


The keyboardType field returns one of the following constants: 


CONST envUnknownKbd = 0; {Macintosh Plus keyboard with keypad} 
envMacKbd =e {Macintosh keyboard} 
envMacAndPad = 2; {Macintosh keyboard and keypad} 
envMacPlusKbd = 3; {Macintosh Plus keyboard} 
envAExtendKbd = 4; {Apple Extended keyboard} 
envStandADBKbd = 5; {Apple Standard keyboard} 
envPortADBKbd = 6; {Macintosh Portable keyboard} 
envPortISOADBKbd = 7; {Macintosh Portable keyboard (ISO) } 
envStdISOADBKbd = 8; {Apple Standard keyboard (1IS0Q)} 
envExtISOADBKbd = 9; {Apple Extended keyboard (IS0)} 


If the Apple Desktop Bus(tm) is in use, this field returns the keyboard type of 
the keyboard on which a keystroke was last made. 


ATDrvrVersNum returns the version number of AppleTalk, if it's been loaded 
(that is, if MPPOpen has been called); otherwise, 0 is returned in this field. 


SysVRefNum returns the working directory reference number (or volume reference 
number) of the directory that contains the currently open System file. 
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LOCALIZATION 


Localization is the process of adapting an application to a specific language 
and country. By making localization relatively painless, you ensure that 
international markets are available for your product in the future. You also 
allow English-speaking users in other countries to buy the U.S. English version 
of your software and use it with their native languages. 


The key to easy localization is to store the country-dependent information used 
by your application as resources (rather than within the application's code). 
This means that text seen by the user can be translated without modifying the 
code. In addition, storing this information in resources means that your 
application can be adapted for a different country simply by substituting the 
appropriate resources. 


iPero, Se Habla Espanol? 


Not all languages have the same rules for punctuation, word order, and 
alphabetizing. In Spanish, questions begin with an upside-down question mark. 
The roles of commas and periods in numbers are sometimes the reverse of what you 
may be used to; in many countries, for instance, the number 3,546.98 is rendered 
3.546,98. 


Laws and customs vary between countries. The elements of addresses don't always 
appear in the same order. In some countries, the postal zone code precedes the 
name of the city, while in other countries the reverse is true. Postal zone 
codes vary in length and can contain letters as well as numbers. The rules for 
amortizing mortgages and calculating interest rates vary from country to 
country-even between Canada and the United States. 


Units of measure and standard formats for time and date differ from country to 
country. For example, "lines per inch" is meaningless in the metric world-that 
is, almost everywhere. In some countries, the 24-hour clock prevails. 


Words aren't the only things that change from country to country. Telephones 
and mailboxes, to name just two examples often used in telecommunications 
programs, don't look the same in all parts of the world. Either make your 
graphics culturally neutral, or be prepared to create alternate graphics for 
various cultures. 


Mnemonic shortcuts (such as Command-key equivalents for menu items) that are 
valid in one language may not be valid in others; be sure all such shortcuts are 
stored as resources. 


Keyboards vary from country to country. Keystrokes that are easily performed 
with one hand in your own country may require two hands in another. In France 
and Italy, for instance, typing numerals requires pressing the Shift key. 


If you rely on properties of the ASCII code table or use data compression codes 
that assume a certain number of letters in the alphabet, remember that not all 
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alphabets have the same numbers of characters. Don't rely on strings having a 
particular length; translation will make most strings longer. (As an example, 
the length of Apple manuals has been known to increase as much as 30% in 
translation.) Also, some languages require two bytes instead of one to store 
characters. 


Non-Roman Writing Systems 


The Script Manager contains routines that allow an application to function 
correctly with non-Roman scripts (or writing systems). It also contains utility 
routines for text processing and parsing, which are useful for applications that 
do a lot of text manipulation. General applications don't need to call Script 
Manager routines directly, but can be localized for non-Roman alphabets through 
such script interface systems as Apple's Kanji Interface System and Arabic 
Interface System. (Scripts and script interface systems are described in the 
Script Manager chapter in this volume.) 


The International Utilities Package provides routines for sorting, comparing 
strings, and specifying currency, measurements, dates, and time. It's better to 
use the routines in this package instead of the Operating System Utility 
routines (which aren't as accurate and can't be localized). 


You should neither change nor depend upon the system font and system font size. 
Some non-Roman characters demand higher resolution than Roman characters. On 
Japanese versions of the Macintosh, for instance, the system font must allow for 
16-by-16 pixel characters. You can use the global variables SysFontFam and 
SysFontSize for determining the system font and system font size. 


The Menu Manager uses the system font and the system font size in setting up the 
height of the menu bar and menu items. Because the system font size can vary, 
the height of the menu bar can also vary. When determining window placement on 
the screen, don't assume that the menu bar height is 20 pixels. Use the global 
variable MBarHeight for determining the height of the menu bar. 


Avoid using too many menus; translation into other languages almost always 
widens menu titles, forcing some far to the right or even off the screen. 


Most Roman fonts for the Macintosh have space above all the letters to allow for 
diacritical marks as with A or N. If text is drawn using a standard font 
immediately below a dark line, for example, it will appear to be separated from 
the line by at least one row of blank pixels (for all but a few exceptional 
characters). Pixels in some non-Roman fonts, on the other hand, extend to the 
top of the font rectangle, and appear to merge with the preceding line. To 
avoid character display overlap, applications should leave blank space around 
text (as in dialog editText or statText items ), or add space between lines of 
text, aS well as before the first line and after the last line of text. 


The choice of script (Roman, Japanese, Arabic, and so on) is determined by the 

fonts selected by the user. If an application doesn't allow the user to change 
fonts, or allows the user to select only a global font for the whole document, 

the user is restricted in the choice and mix of scripts. 
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If text must be displayed in either uppercase or lowercase, you should call the 
Script Manager Transliterate routine rather than the UprString routine (which 
doesn't handle diacritical marks or non-Roman scripts correctly). 
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APPLICATIONS IN A SHARED ENVIRONMENT 


A number of new products create environments in which users can share 
information. Network file servers (like AppleShare(tm)), for instance, make it 
possible for users to share data, applications, and disk storage space. 
Multitasking operating systems and programs like MultiFinder can also be 
considered shared environments, allowing data to be shared between applications. 


To operate smoothly in a shared environment, you'll need to be sensitive to 
issues like multiple file access, access privileges, and multiple launches. For 
a complete discussion of how to operate in shared environments, see the File 


Manager chapter. 
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SUMMARY OF COMPATIBILITY GUIDELINES 


Data Type 


TYPE SysEnvRec = RECORD 
environsVersion: INTEGER; 


machineType: INTEGER; 
systemVersion: INTEGER; 
processor: INTEGER; 
hasFPU: BOOLEAN; 
hasColorQD: BOOLEAN; 
keyBoardType: INTEGER; 
atDrvrVersNum: INTEGER; 
sysVRefNum: INTEGER 
END; 


Routine 


FUNCTION SysEnvirons (versionRequested: INTEGER; 
VAR theWorld: SysEnvRec) : OSErr; [Not in ROM] 


Result Codes 


Name Value Meaning 
noErr 0 No error 
envNotPresent -5500 SysEnvirons trap not present (System File earlier 


than version 4.1); glue returns values for all 
fields except systemVersion 


envBadVers -5501 A nonpositive version number was passed-no 
information is returned 

envVersTooBig -5502 Requested version of SysEnvirons call was not 
available 


Assembly-Language Information 


Structure of System Environment Record 


environsVersion (word) 
machineType (word) 
systemVersion (word) 
processor (word) 
hasFPU (byte) 
hasColorQD (byte) 
keyBoardType (word) 
atDrvrVersNum (word) 
sysVRefNum (word) 
sysEnvRecSize Size of system environment record 
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Routine 


Trap macro On entry On exit 

_SysEnvirons AQ: sysEnvRecPtr (ptr) AQ: sysEnvRecPtr (ptr) 
DO: versRequested (word) DO: result code (word) 

Variables 

ApplZone Address of application heap zone 

MBarHeight Height of menu bar (word) 

MemTop Address of end of RAM 

ScreenBits Bit map of screen in use (bitMapRec bytes) 

SysZone Address of system heap zone 

Ticks Current number of ticks since system startup (long) 
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File Manager 
Script Manager 
Note #129, SysEnvirons: System 6.0 and Beyond 


Technical 
Technical 
Technical 
Technical 
Technical 
Technical 
Technical 
Technical 


Note #176, Macintosh Memory Configurations 
Note #180, MultiFinder Miscellanea 

Note #208, Setting and Restoring A5 

Note #212, The Joy Of Being 32-Bit Clean 
Note #227, Toolbox Karma 


Note #230, Pertinent Information About the Macintosh SE/30 


Note #258, Our Checksum Bounced 
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